<html>
<head><meta charset="utf-8"><title>clap-doc · wg-cli · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/index.html">wg-cli</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html">clap-doc</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="191716008"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191716008" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191716008">(Mar 25 2020 at 09:08)</a>:</h4>
<p>(Just thinking aloud, feel free to join)</p>



<a name="191716452"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191716452" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191716452">(Mar 25 2020 at 09:13)</a>:</h4>
<p>I doubt that attracting extra attention to certain functions will fix the situation unless it's based on statically significant data, which we don't have.</p>
<p>A FAQ (this is essentially what <span class="user-mention" data-user-id="254853">@pksunkara</span> proposes), in order to be useful, needs to focus reader's  attention on the minority of topics that are asked most, leaving everything else out of sight. </p>
<p>To identify these commonly asked topics, we would need to gather significant number of help requests/complaints. So far, we've only had 10 or so. And they are fairly broad; I recall <code>conflicts</code>, <code>requires</code>, <code>raw</code>, <code>groups</code>, <code>aliases</code>, yadda, yadda. We don't have the data to write a useful FAQ at this point.</p>



<a name="191716756"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191716756" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191716756">(Mar 25 2020 at 09:16)</a>:</h4>
<p>Alternative proposal: encourage users to help each other with simple questions (like, what do I use to express "any of those, but not others?"). I think we should aggressively advertise the gitter chat.</p>



<a name="191716870"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191716870" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191716870">(Mar 25 2020 at 09:17)</a>:</h4>
<p>And only if the community haven't come up with anything satisfying, tell them to go to the issue tracker. This should significantly reduce the load for maintainers.</p>



<a name="191717056"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191717056" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191717056">(Mar 25 2020 at 09:19)</a>:</h4>
<p>Of course, this doesn't' mean that the doc is perfect and needs no improvement.</p>



<a name="191717239"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191717239" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191717239">(Mar 25 2020 at 09:20)</a>:</h4>
<p>I mean, the documentation is <em>mostly</em> fine, it's just there's a lot of it. Users, as <span class="user-mention" data-user-id="131358">@spacekookie</span> pointed out,  get drowned in it.</p>



<a name="191717586"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191717586" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191717586">(Mar 25 2020 at 09:23)</a>:</h4>
<p>We need... well , ideally, we would need a <em>concise</em> list of... pointers?</p>



<a name="191717824"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191717824" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191717824">(Mar 25 2020 at 09:26)</a>:</h4>
<p>It's like, we've already had a road, now we need waymarks.</p>



<a name="191717847"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191717847" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191717847">(Mar 25 2020 at 09:26)</a>:</h4>
<p>Any ideas?</p>



<a name="191717894"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191717894" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191717894">(Mar 25 2020 at 09:26)</a>:</h4>
<p>Also, the point of many of our user being newbies.</p>



<a name="191718204"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191718204" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191718204">(Mar 25 2020 at 09:29)</a>:</h4>
<p>Maybe some sort of book describing the process of an application creation.</p>



<a name="191718404"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191718404" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191718404">(Mar 25 2020 at 09:30)</a>:</h4>
<p>It should touch on most requested (except, as I said, we don't really know what those are) <code>conflicts</code>, <code>subcommand</code>, <code>alisaes</code>, <code>requirements</code>. Anything else?</p>



<a name="191889348"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/191889348" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> pksunkara <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#191889348">(Mar 26 2020 at 14:08)</a>:</h4>
<p>I think we should do both, add a minimal FAQ and encourage users to participate in community chat</p>



<a name="192261272"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/192261272" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> spacekookie <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#192261272">(Mar 30 2020 at 14:15)</a>:</h4>
<p>So I think an FAQ is a really good idea, and we should look through the docs that already exist and see how they can be made easier to navigate. I feel like maybe reducing the README down to a minimal example that people can just copy and paste in most situations, and then moving stuff into a docs folder tree (or wiki) might be a good idea.</p>
<p>I for one usually end up looking for the same three things that are kinda buried in the hay stack</p>



<a name="192261293"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/192261293" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> spacekookie <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#192261293">(Mar 30 2020 at 14:15)</a>:</h4>
<p>Or well...markdown stack :P</p>



<a name="192262787"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/192262787" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#192262787">(Mar 30 2020 at 14:26)</a>:</h4>
<p>Shortening the README? Yes please. It's so long and looks so close to a documentation that some (I repeat, not enough data to make actual claims here) people confuse it with the actual documentation/examples.</p>



<a name="192262981"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/192262981" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#192262981">(Mar 30 2020 at 14:27)</a>:</h4>
<p>We can write a FAQ based on experience of our own, and then correct it as the we receive feedback.</p>



<a name="192263073"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/192263073" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> CreepySkeleton <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#192263073">(Mar 30 2020 at 14:28)</a>:</h4>
<blockquote>
<p>I for one usually end up looking for the same three things</p>
</blockquote>
<p>Those being?</p>



<a name="192328301"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/220302-wg-cli/topic/clap-doc/near/192328301" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> pksunkara <a href="https://rust-lang.github.io/zulip_archive/stream/220302-wg-cli/topic/clap-doc.html#192328301">(Mar 30 2020 at 23:04)</a>:</h4>
<p>I am currently talking to someone about activating the discussions feature for our github repo. Hopefully that might help.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>